home *** CD-ROM | disk | FTP | other *** search
/ NetNews Offline 2 / NetNews Offline Volume 2.iso / news / comp / sys / amiga / programmer / 4648 < prev    next >
Encoding:
Internet Message Format  |  1996-08-05  |  15.1 KB
  1. From: magicsn@birdland.es.bawue.de (Steffen Haeuser)
  2. Path: eisbaer.bb.bawue.de!birdland.es.bawue.de
  3. Newsgroups: comp.sys.amiga.programmer
  4. Message-ID: <00000405732623060000@BIRDLAND>
  5. X-Mailer: fastnet2rfc V2.0 - (tse) Lunqual%MAB@wsb.freinet.de / Tachy@wsb.freinet.de
  6. Organization: Birdland BBS, Dettingen/Teck, South Germany, +49-7021-862428
  7. Content-Type: text/plain; charset=ISO-8859-1
  8. Subject: rtgmaster c2p complete rework :)
  9. Date: 01 Mar 1996 23:31:46
  10.  
  11. Sorry, that the docs i sent were a bit ... buggy... i now reworked
  12. the whole thing completely... but still "Beta, to be commented
  13. from people who know about what they are talking (c2p authors...)"
  14. If it changes, the final version will be somewhen available together
  15. with rtgmaster.library...
  16.  
  17. The RtgMaster c2p Standard V 1.0
  18. ================================
  19.  
  20. 1. What is it/What is rtgmaster ?
  21. 2. The Structure of a RtgMaster c2p File
  22. 3. The Functions and its specification
  23. 4. The specification of the data
  24. 5. How will this be used in an application ?
  25. 6. Error Handling
  26. 7. Includes
  27. 8. A word from the Authors
  28.  
  29. ---------------------------------------------------------------------------
  30.  
  31. 1. What is it/What is rtgmaster ?
  32. =================================
  33.  
  34. rtgmaster.library is a soon to be released ASM written Library for
  35. Graphicsboard AND ECS/AGA compatibility in games and demos. It is
  36. NOT a WB Emulation, but contrary to some WB Emulations it is done
  37. in a way that make that things, that demo/game coders need, EASY
  38. TO DO.
  39.  
  40. Among its features, rtgmaster.library (a Beta version is available
  41. from me, MagicSN@birdland.es.bawue.de), supports a standard for
  42. c2p functions. This will used with the rtgmaster call CallRtgC2P.
  43. CallRtgC2P performs a simple "CopyPixelArray" style function for
  44. Graphics Boards (but does not use the OS, instead it directly
  45. accesses the Video Memory, using longword access where possible),
  46. and performs c2p for ECS/AGA. The c2p is choosable from a file
  47. and the c2p function will be loaded during opening the screen.
  48. This file describes how you can change your c2p algorithm so that
  49. it is usable with rtgmaster.library (you can choose the c2p using
  50. the Screenmode Requester of rtgmaster.library).
  51.  
  52. I want to note, that anybody who has converted his c2p functions
  53. to the rtgmaster standard, should send them to me, so that they
  54. can be included to the rtgmaster package as soon as it is
  55. released.
  56.  
  57. And, by the way... forget about that earlier "rtgmaster c2p standard"
  58. document... that was only a first try :) (Bad documentation,
  59. bad functionality, bad structure...) This here is the real thing.
  60.  
  61. ----------------------------------------------------------------------------
  62.  
  63. 2. The Structure of a Rtgmaster c2p File
  64. ========================================
  65.  
  66. Primarily this is a file that will be loaded to the memory using dos.library
  67. call LoadSeg(). After being loaded in, it looks somewhat like :
  68.  
  69.         moveq   #0,d0
  70.         rts
  71. .s      dc.l    "c2p!"
  72.         dc.l    .s
  73.         dc.l    1               ; Versionnumber
  74.         dc.l    Structure       ; Pointer to your data structure
  75.  
  76. Structure is of Type c2p_Info.
  77.  
  78. STRUCTURE c2p_Info,0
  79.      WORD    CI_ColorDepth           ;CI_256, CI_128, CI_64, CI_EHB, CI_32..
  80.      WORD    CI_CPU                  ;CI_68060, CI_68040, CI_68030....
  81.      WORD    CI_Needs                ;CI_Aikiko, CI_MMU, CI_FPU...
  82.      UBYTE   CI_PixelSize            ;CI_1x1, CI_1x2, CI_2x1, CI_2x2...
  83.      BOOL    CI_Dirty                ;TRUE/FALSE
  84.      BOOL    CI_Hack                 ;TRUE/FALSE
  85.      BOOL    CI_Asynchrone           ;TRUE/FALSE
  86.      WORD    CI_WidthAlign           ;Width has to be divisible by <number>
  87.      WORD    CI_HeightAlign          ;Height has to be divisible by <number>
  88.      WORD    CI_Misc                 ;Different stuff...
  89.      ULONG   CI_AmiCompatible        ;Is this compatible to RtgScreenAMI ?
  90.      APTR    CI_Description          ;Pointer to a string
  91.      APTR    CI_Initialization       ;Pointer to Initialization code
  92.      APTR    CI_Expunge              ;Pointer to Expunge code
  93.      APTR    CI_Normal_c2p           ;Pointer to c2p code
  94.      APTR    CI_Normal_c2p_InterL    ;Pointer to Interleaved c2p
  95.      APTR    CI_Scrambled_c2p        ;Pointer to Scrambled c2p
  96.      APTR    CI_Scrambled_c2p_InterL ;Pointer to Scrambled Interleaved c2p
  97.      LABEL   CI_SIZEOF
  98.  
  99.  
  100. In the following chapters, it will be discussed how all those entries look
  101. like, how they will be used by rtgmaster.library, how they have to be coded,
  102. what error messages have to supported and related issues.
  103.  
  104. ----------------------------------------------------------------------------
  105.  
  106. 3. The functions and its specification
  107. ======================================
  108.  
  109. To support rtgmaster c2p, you will need some or more of the functions :
  110.  
  111. * CI_Initialization
  112. * CI_Expunge
  113. * CI_Normal_c2p
  114. * CI_Normal_c2p_InterL
  115. * CI_Scrambled_c2p
  116. * CI_Scrambled_c2p_InterL
  117.  
  118. CI_Initialization
  119. -----------------
  120.  
  121. Some c2p algorithms need an initialization part, to allocate extra Buffers,
  122. to calculate initialization conditions and similar things. This will be the
  123. place where to do this.
  124.  
  125. You will get a parameter in a0, when this function is called. This parameter
  126. is a pointer to the RtgScreenAMI structure of the Screen, to which the c2p algorithm is
  127. to attach. There can only be one c2p algorithm installed in a system, but
  128. it can be changed as soon as a Screenmode-Requester of rtgmaster.library
  129. is opened (But the c2p of an already running program won't change).
  130.  
  131. The CI_Initialization code will be called from the OpenRtgScreen function
  132. of rtgAMI.library, the rtgmaster sublibrary for ECS/AGA.
  133.  
  134. This c2p format only supports Planar rtgmaster Sublibraries whose RtgScreen
  135. structure is compatible to RtgScreenAMI, but anyways, there do not exist
  136. Planar sublibraries for other hardware. Coders of guessed future Planar
  137. Graphics Sublibraries should be sure, that at least the entries
  138.  
  139. * rsAMI_ScreenHandle
  140. * rsAMI_PlaneSize
  141. * rsAMI_Bitmap1
  142.  
  143. will be at the same place for their sublibraries, if they want to use
  144. existing c2p code. If that is not possible, they should check in their
  145. sublibrary's CallRtgC2P code for CI_AmiCompatible (more information in
  146. the chapter about the Rtgmaster c2p data structures).
  147.  
  148. You might save any stuff that is allocated during the initialization part
  149. in rs_c2pcode(a0), where a0 is the before mentioned pointer to the given
  150. RtgScreenAMI structure.
  151.  
  152. If your c2p code does not need any initialization, simply give 0 as the
  153. pointer to the initialization code.
  154.  
  155. Parameters :
  156.  
  157. a0.l = Pointer to RtgScreenAMI
  158.  
  159. Output :
  160.  
  161. d0.l = 0, if failed, else 1
  162.  
  163. CI_Expunge
  164. ----------
  165.  
  166. This function returns any system resources and memory to where they belong.
  167. It is called during CloseRtgScreen of rtgAMI.library. You will get a pointer
  168. to the RtgScreenAMI structure of the Screen, to which the c2p was attached,
  169. in a0.
  170.  
  171. Parameters :
  172.  
  173. a0.l = Pointer to RtgScreenAMI
  174.  
  175. Output :
  176.  
  177. d0.l = 0, if failed, else 1
  178.  
  179. CI_Normal_c2p
  180. -------------
  181.  
  182. This is the c2p main function for non-interleaved screens with contintiguous
  183. Bitmaps. As this c2p code supports rtgmaster.library, it might use up to three
  184. buffers, but that might not bother you, you will already get the correct
  185. Bitplane 0 Base addresses by CallRtgC2P.
  186.  
  187. CI_Normal_c2p_InterL works much the same way, only that it is intended for
  188. interleaved Screens. It is possible to include functions for all four types
  189. of c2p functions to one c2p file. CallRtgC2P will call the correct one.
  190.  
  191. Parameters :
  192.  
  193. a0.l = Pointer to the Chunky Data
  194. a1.l = Pointer to Bitplane 0
  195. a2.l = Pointer to a Byte containing the "Dirty" Flag (see below)
  196. a3.l = Pointer to the RtgScreenAMI structure, to which the c2p should be attached
  197. a4.l = Pointer to a Rectangle, like defined in include:graphics/gfx.i, which
  198.        specifies, which region of the display the c2p should handle, or 0, if
  199.        fullscreen c2p was intended.
  200. d0.l = c2p Modus (see below)
  201. d1.l = Planesize : (width*height)/8
  202. d2.l = An exec signal, for asynchrone c2p
  203.  
  204. Now, what should such a function do ? At first it should do error-handling,
  205. like described in a later chapter, after that it should perform c2p, and as
  206. soon as it is finished it should signal the waiting task, that it is finished.
  207. This way, you are able to implement asynchrone c2p. Even synchrone c2p algorithms
  208. have to signal the task, else it waits forever.
  209.  
  210. Output :
  211.  
  212. d0.l = 0, if everything worked, else error-code (see below)
  213.  
  214. CI_Scrambled_c2p
  215. ----------------
  216.  
  217. This is the c2p main function for non-interleaved screens with Bitmaps, that
  218. use "scrambled" c2p. These are algorithms, where the bitplanes are not in the
  219. normally assumed order. They should still be contiguous, though. To set a standard,
  220. I have to admit, i do not know much about scrambled c2p, only that Gloom Deluxe
  221. uses it, and therefor it is specified, that rtgmaster scrambled c2p has to use
  222. the same Bitplane order as this is done for Gloom Deluxe c2p. For more information
  223. about Gloom Deluxe c2p, get GloomC2P10.lha from Aminet.
  224.  
  225. It is strongly discouraged to write scrambled-only c2p, as then the coder using
  226. the c2p can't use the same chunky buffer for Graphics Boards and AGA, as CallRtgC2P
  227. does a fast "Write from Fastram-Buffer to Video-RAM" instead of c2p-ing. The user
  228. will be told, that this c2p won't work with all programs, if he chooses a scrambled
  229. chunky c2p, and he will be asked, if he wants to select the Scrambled or the Non-scrambled
  230. code, if both are available for a Rtgmaster c2p File. Scrambled c2p sometimes might
  231. be faster than non-scrambled c2p.
  232.  
  233. The Parameters and output are the same as for non-scrambled c2p, and there, too, exist
  234. too types of c2p, for non-interleaved and for interleaved Bitmaps.
  235.  
  236. ----------------------------------------------------------------------------------------------
  237.  
  238. 4. The specification of the data
  239. ================================
  240.  
  241. STRUCTURE c2p_Info,0
  242.      WORD    CI_ColorDepth           ;CI_256, CI_128, CI_64, CI_EHB, CI_32..
  243.      WORD    CI_CPU                  ;CI_68060, CI_68040, CI_68030....
  244.      WORD    CI_Needs                ;CI_Aikiko, CI_MMU, CI_FPU...
  245.      UBYTE   CI_PixelSize            ;CI_1x1, CI_1x2, CI_2x1, CI_2x2...
  246.      BOOL    CI_Dirty                ;TRUE/FALSE
  247.      BOOL    CI_Hack                 ;TRUE/FALSE
  248.      BOOL    CI_Asynchrone           ;TRUE/FALSE
  249.      WORD    CI_WidthAlign           ;Width has to be divisible by <number>
  250.      WORD    CI_HeightAlign          ;Height has to be divisible by <number>
  251.      WORD    CI_Misc                 ;Different stuff...
  252.      ULONG   CI_AmiCompatible        ;Is this compatible to RtgScreenAMI ?
  253.      APTR    CI_Description          ;Pointer to a string
  254.      APTR    CI_Initialization       ;Pointer to Initialization code
  255.      APTR    CI_Expunge              ;Pointer to Expunge code
  256.      APTR    CI_Normal_c2p           ;Pointer to c2p code
  257.      APTR    CI_Normal_c2p_InterL    ;Pointer to Interleaved c2p
  258.      APTR    CI_Scrambled_c2p        ;Pointer to Scrambled c2p
  259.      APTR    CI_Scrambled_c2p_InterL ;Pointer to Scrambled Interleaved c2p
  260.      LABEL   CI_SIZEOF
  261.  
  262. * CI_Colordepth : Contains the Colordepths supported by this c2p algorithm.
  263.  
  264. CI_256 : AGA 256 colors
  265. CI_128 : AGA 128 colors
  266. CI_64  : AGA 64  colors
  267. CI_EHB : ECS 64  colors (EHB)
  268. CI_32  : ECS 32  colors
  269. CI_16  : ECS 16  colors
  270. CI_8   : ECS 8   colors
  271. CI_4   : ECS 4   colors
  272. CI_2   : ECS 2   colors
  273.  
  274. There might be more available bits, if future Amigas support more Planar
  275. modes. Therefor i choose a WORD for this structure.
  276.  
  277. If a c2p is run and a screen with the wrong colour depth is opened, the
  278. c2p operation fails. (see below)
  279.  
  280. * CI_CPU : Contains information about the supported CPU.
  281.  
  282. CI_68060 : Runs on 68060.
  283. CI_68040 : Runs on 68040.
  284. CI_68030 : Runs on 68030.
  285. CI_68020 : Runs on 68020.
  286.  
  287. These bits are set, if it runs, cleared, if not. As rtgmaster.library
  288. needs 68020 at least, no Bits for 68000/68010.
  289.  
  290. CI_68060D : Don't know, if it runs on 68060.
  291. CI_68040D : Don't know, if it runs on 68040.
  292. CI_68030D : Don't know, if it runs on 68030.
  293. CI_68020D : Don't know, if it runs on 68020.
  294.  
  295. This might be expanded in the future, as soon as Power PC Amigas
  296. with 680x0 emulations will appear.
  297.  
  298. * CI_Needs : Some c2p needs special hardware to run.
  299.  
  300. CI_68060N : 68060 only code.
  301. CI_68040N : Needs 68040 at least.
  302. CI_68030N : Needs 68030 at least.
  303. CI_Aikiko : Needs Aikiko.
  304. CI_MMU    : Needs an MMU.
  305. CI_FPU    : Needs an FPU.
  306.  
  307. This might be expanded in the future.
  308.  
  309. Notice, that the hardware won't be checked for the correct cpu, but
  310. the information will be given to the user. Maybe it will be checked
  311. when the user selects the c2p for his system in a future version of
  312. rtgmaster.library. (see below)
  313.  
  314. * CI_PixelSize : Which Pixelsizes are supported by the c2p.
  315.  
  316. c2p_1x1
  317. c2p_1x2
  318. c2p_2x1
  319. c2p_2x2
  320. c2p_2x4
  321. c2p_4x2
  322. c2p_4x4
  323.  
  324. are the types for which the "Dirty" Flag will be ignored. The Dirty
  325. Flag specifies (if set), that not all CI_WidthAlign Pixels have to be
  326. processed, if not needed.
  327.  
  328. c2p_1x1D
  329. c2p_1x2D
  330. c2p_2x1D
  331. c2p_2x2D
  332. c2p_2x4D
  333. c2p_4x2D
  334. c2p_4x4D
  335.  
  336. are the types that try to use the "Dirty" Flag. It could still be set to
  337. 0, though.
  338.  
  339. c2p_Best and c2p_BestD try to use the highest resolution mode.
  340. c2p_Fastest and c2p_FastestD try to use the fastest ones.
  341. c2p_Selected and c2p_SelectedD try to use the one selected by the user
  342. as standard c2p.
  343.  
  344. You will have to check yourselves, if the ordered mode is existing in
  345. this c2p (see below).
  346.  
  347. * CI_Dirty : Specifies if this c2p supports a dirty flag. It can be
  348.   true (1) or false (0).
  349.  
  350. * CI_Hack : Specifies, if this c2p uses some ugly hardware hacks, that
  351.   might not run on Intuition Screens. It then only will be used with
  352.   a still not existing hardware-banging RtgScreenAMI compatible
  353.   rtgmaster sublibrary. Only specify this, if it REALLY does not run
  354.   with Intuition Screens. Planar sublibraries that are for hardware
  355.   other than ECS/AGA, will fail, if trying to use such c2p code.
  356.   Can be true (1) or false (0).
  357.  
  358. * CI_Asynchrone : Specifies, if the c2p code is asynchrone (1) or
  359.   synchrone (0).
  360.  
  361. * CI_WidthAlign : Specifies, if the c2p code needs a screen whose width
  362.   is divisible by a certain number. This value contains this number, or
  363.   0, if this is not needed.
  364.  
  365. * CI_HeightAlign : The same for the height.
  366.  
  367. * CI_Misc :
  368.  
  369.   CI_Smaller : If this bit is set, the c2p algorithm supports c2p-ing
  370.   rectangles that are smaller than Full-Screen.
  371.  
  372.   CI_Misc might be expanded in the future.
  373.  
  374. * CI_AmiCompatible : Contains 'AMI ', if this c2p code is compatible
  375.   with RtgScreenAMI. If not, it contains the code of the sublibrary
  376.   with that it is compatible (three letters + blank or four letters).
  377.  
  378. * CI_Description : Points to a string discribing this c2p algorithm.
  379.   Up to 255 letters, 0-terminated.
  380.  
  381. ----------------------------------------------------------------------------------------------
  382.  
  383. 5. How will this be used in an application ?
  384. ============================================
  385.  
  386. Normally this c2p will be called using rtgmaster.library function CallRtgC2P.
  387. I am including the Autodocs for CallRtgC2P at the end of this chapter. People
  388. who are interested in rtgmaster.library, should mail me at MagicSN@birdland.es.bawue.de
  389.  
  390. The c2p code is integrated the following way :
  391.  
  392. 1. The user selects a c2p code to be used for his systemusing the rtgmaster
  393.    Screenmode Requester. The Path of this file will be stored in envarc:rtgmaster/c2p.
  394.    Then he chooses a default mode, that will be stored in envarc:rtgmaster/c2pcurr. (=> Next mail)
  395.